Stable Captives / NoeActorClone API 6
=====================================

Technical filenames and API names remain NoeActorClone. "Stable Captives" is
only the public mod and MCM name.

1. Existing clone flags (unchanged from API 5)
------------------------------------------------

    ActorBase targetBase = NoeActorClone.CloneBaseWithFlags(source, cloneFlags)

cloneFlags is a bit mask:
- 0: copy neither inventory nor outfit
- 1: allow the owner mod to copy the live Actor-reference inventory
- 2: copy the ActorBase default and sleep outfits in the DLL
- 3: both

Inventory belongs to the live Actor reference. Therefore DOM/PAHE should run
its existing inventory transfer only when bit 1 is present. The included test
integration still uses cloneFlags = 0 by default. A future DOM MCM option only
needs to construct a value from 0 to 3.

After Actor creation and CommitClone(), call FinalizeManagedClone(). It keeps
or detaches base outfits according to bit 2 and queues visual refresh.

2. Optional ActorBase flags and level configuration
----------------------------------------------------

ConfigureActorBase() is optional. If it is not called, the resolved source
ActorBase values are preserved, except for Stable Captives' identity rules:
Unique is forced on, and Respawn plus UsesTemplate are forced off.

Call it only after CloneBase/CloneBaseWithFlags returns a reserved ActorBase
and before CommitClone:

    ActorBase targetBase = NoeActorClone.CloneBaseWithFlags(source, cloneFlags)
    if targetBase
        bool configured = NoeActorClone.ConfigureActorBase(
            targetBase,
            flagsToSet,
            flagsToClear,
            pcLevelMult,
            fixedLevel,
            minLevel,
            maxLevel)

        if configured
            ; Create the Actor from targetBase, then CommitClone(actor).
        else
            NoeActorClone.CancelCloneBase(targetBase)
        endif
    endif

Arguments
- flagsToSet / flagsToClear: supported ActorBase bit masks below.
- pcLevelMult: -1 preserves it; 0.001..65.535 enables PC Level Mult.
- fixedLevel: -1 preserves it; 1..65535 disables PC Level Mult and sets level.
- minLevel / maxLevel: -1 preserves each value; otherwise 0..65535.
- pcLevelMult and fixedLevel cannot both be supplied.
- Enabling bit 128 requires pcLevelMult. Clearing bit 128 requires fixedLevel.

Supported editable flag bits
- 2 Essential
- 16 Auto Calc Stats
- 64 Doesn't Affect Stealth
- 128 PC Level Mult
- 2048 Protected
- 16384 Summonable
- 65536 Doesn't Bleed
- 262144 Bleedout Override
- 524288 Opposite Gender Animations
- 1048576 Simple Actor
- 2097152 Looped Script
- 268435456 Looped Audio
- 536870912 Ghost
- -2147483648 Invulnerable (signed Papyrus Int form of 0x80000000)

Examples

Preserve source values:
    Do not call ConfigureActorBase().

Set PC Level Mult to 1.0 and level range 10..100:
    NoeActorClone.ConfigureActorBase(targetBase, 128, 0, 1.0, -1, 10, 100)

Use fixed level 25 when the source used PC Level Mult:
    NoeActorClone.ConfigureActorBase(targetBase, 0, 128, -1.0, 25, -1, -1)

Stable Captives intentionally does not impose a follower preset. DOM/PAHE can
choose its own defaults. Essential and Protected are source-preserving unless
the owner integration explicitly changes them.

3. Slot allocation and release
-------------------------------

- GetAPIVersion() returns 6.
- The 1,024-slot pool uses a persisted circular search origin.
- A slot is globally leased and marked Reserved before FaceGen or ActorBase
  data is copied.
- A full circular pass with no free slot returns None.
- CancelCloneBase() releases an uncommitted reservation.
- ReleaseActorBase() is only for confirmed permanent Actor deletion. It moves
  the slot to Retiring; the lease is returned only after the reference no
  longer resolves, preventing premature reuse during DeleteWhenAble().

4. Scope boundary
-----------------

The DLL does not modify factions, dialogue, quest aliases, AI packages,
relationships, slave state, equipment decisions, or Actor-reference ownership.
Those remain entirely under DOM, PAHE, HSH, and AYGAS control.

